/**
 * 
 * ETH AI GAME LIBRARY
 * 
 * Author: Michael Jaworski
 * Copyright (c) Michael Jaworski 2010
 * http://code.google.com/p/eth/
 * 
 * Licence Agreement
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *	
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 *
 */

package lib.eth.core.types
{
	
	/**
	 * A bit flag. Used for efficient storage of groups of boolean
	 * values.
	 *
	 * @version 0.1
	 * @see lib.eth.core.types.EthEnum 
	 * 
	 * 
	 * <pre>
	 * EthBitFlag Example
	 * 
	 * ...
	 * class RankEnum extends EthEnum 
	 * {
	 *   public static const GENERAL:GameEnum 		= new GameEnum (GENERAL, 1);
	 *   public static const COLONEL:GameEnum 		= new GameEnum (COLONEL, 2);
	 *   public static const LIEUTENANT:GameEnum 	= new GameEnum (LIEUTENANT, 4);
	 *   public static const CORPORAL:GameEnum 		= new GameEnum (CORPORAL, 8);
	 *   public static const PRIVATE:GameEnum 		= new GameEnum (PRIVATE, 16);
	 * }
	 * ...
   *
 	 * var informFlag:EthBitFlag = new EthBitFlag ();
	 *  
	 * informFlag.raise (RankEnum.GENERAL);
	 * informFlag.raise (RankEnum.CORPORAL);
	 * 
	 * if (informFlag.flagged (RankEnum.PRIVATE))
	 * {
	 * 	 // have private act or read another message - otherwise he ignores command
	 * }
	 * </pre>
	 * 
	 */ 
	public class EthBitFlag
	{
		/**
		 * 
		 * holds up to 32 binary values  
		 * 
		 */
		private var _flag:uint;
		
		/**
		 * 
		 * the flag is set to all zero values
		 * 
		 */ 
		public function EthBitFlag ()
		{
			_flag = 0;
		}
				
		/**
		 * the enumeration value is used (must be 1, 2, 4, ...) to target
		 * the binary value being raised. 
		 *
		 * <p>
		 * pre  : the bit at position ethFlagIn is 0 or 1<br />
		 * post : the bit at position ethFlagIn is 1
		 * </p>
		 * 
		 * @param ethFlagIn use the EthEnum class to create a class of EthEnum constants and pass
		 * one of those constants in
		 *  
		 */ 
		public function set raise (ethFlagIn:EthEnum) : void
		{
			_flag = _flag | ethFlagIn.flag;
		}
		
		/**
		 * the enumeration value is used (must be 1, 2, 4, ...) to target
		 * the binary value being lowered. 
		 *
		 * <p>
		 * pre  : the bit at position ethFlagIn is 0 or 1<br />
		 * post : the bit at position ethFlagIn is 0
		 * </p>
		 *  
		 * @param ethFlagIn use the EthEnum class to create a class of EthEnum constants and pass
		 * one of those constants in
     *
		 */ 
		public function set lower (ethFlagIn:EthEnum) : void
		{
			_flag = _flag & (~ethFlagIn.flag);
		}
		
		/**
		 * 
		 * @param ethFlagIn the flag to test against this flag
		 * 
		 * @return true if the ethFlagIn has the same bits up as the comparison flag
		 * 
		 */
		public function flagged (ethFlagIn:EthEnum) : Boolean
		{
			return ((_flag & ethFlagIn.flag) == ethFlagIn.flag); 
		}
		
		/**
		 * 
		 * @param ethFlagIn the flag to test against this flag
		 * 
		 * @return true if the ethFlagIn has the same bits up as the comparison flag
		 * 
		 */
		public function equal (ethFlagIn:EthBitFlag) : Boolean
		{
			return ((_flag & ethFlagIn._flag) == ethFlagIn._flag); 
		}		
		
		/**
		 * 
		 * @return a binary representation of the bitflag
		 * 
		 */
		public function toString () : String
		{ 
			return _flag.toString (2); 
		}		
	}
}